jws

What is jws?

The jws npm package is a JavaScript implementation for JSON Web Signatures (JWS). It allows you to create, verify, and work with JWSs. This package is useful for implementing security features in applications, such as token-based authentication and data integrity checks.

What are jws's main functionalities?

Signing

This feature allows you to create a JWS by providing a payload, a secret (or private key), and an algorithm. The package will generate a signature that can be used to verify the payload's integrity and authenticity.

{"alg":"HS256","typ":"JWT"}.{"name":"John Doe"}.HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), 'secret')

Verification

This feature allows you to verify a JWS signature using the provided secret (or public key) and the algorithm. It returns a boolean indicating whether the signature is valid.

jws.verify(signature, algorithm, secretOrPublicKey)

Decoding

This feature allows you to decode a JWS to extract the header and payload without verifying the signature. This is useful for cases where you need to read the payload without necessarily trusting its source.

jws.decode(signature)

Other packages similar to jws

jsonwebtoken

jsonwebtoken is a popular npm package that provides similar functionality to jws. It allows you to encode and decode JSON Web Tokens (JWTs) which are an extension of JWS. It includes additional features for handling token expiration, audience, issuer, and other JWT claims.

jose

jose is a comprehensive library for JSON Object Signing and Encryption (JOSE). It supports JWS, JSON Web Encryption (JWE), JSON Web Key (JWK), and JSON Web Algorithms (JWA). It offers a wider range of cryptographic operations compared to jws.

node-jose

node-jose is another library that provides JOSE functionalities in Node.js. It is similar to the 'jose' package but is designed specifically for Node.js environments. It supports JWS, JWE, JWK, and JWA, and it is built to work well with other Node.js modules and async patterns.

README

node-jws

An implementation of JSON Web Signatures.

This was developed against draft-ietf-jose-json-web-signature-08 and implements the entire spec except X.509 Certificate Chain signing/verifying (patches welcome).

There are both syncronous (jws.sign, jws.verify) and streaming (jws.createSign, jws.createVerify) APIs.

Install

$ npm install jws

Usage

jws.ALGORITHMS

Array of supported algorithms. The following algorithms are currently supported.

alg Parameter Value	Digital Signature or MAC Algorithm
HS256	HMAC using SHA-256 hash algorithm
HS384	HMAC using SHA-384 hash algorithm
HS512	HMAC using SHA-512 hash algorithm
RS256	RSASSA using SHA-256 hash algorithm
RS384	RSASSA using SHA-384 hash algorithm
RS512	RSASSA using SHA-512 hash algorithm
ES256	ECDSA using P-256 curve and SHA-256 hash algorithm
ES384	ECDSA using P-384 curve and SHA-384 hash algorithm
ES512	ECDSA using P-521 curve and SHA-512 hash algorithm
none	No digital signature or MAC value included

jws.sign(options)

(Synchronous) Return a JSON Web Signature for a header and a payload.

Options:

• header
• payload
• secret or privateKey
• encoding (Optional, defaults to 'utf8')

header must be an object with an alg property. header.alg must be one a value found in jws.ALGORITHMS. See above for a table of supported algorithms.

If payload is not a buffer or a string, it will be coerced into a string using JSON.stringify.

Example

const signature = jws.sign({
  header: { alg: 'HS256' },
  payload: 'h. jon benjamin',
  secret: 'has a van',
});

jws.verify(signature, secretOrKey)

(Synchronous) Returnstrue or false for whether a signature matches a secret or key.

signature is a JWS Signature. secretOrKey is a string or buffer containing either the secret for HMAC algorithms, or the PEM encoded public key for RSA and ECDSA.

jws.decode(signature)

(Synchronous) Returns the decoded header, decoded payload, and signature parts of the JWS Signature.

Returns an object with three properties, e.g.

{ header: { alg: 'HS256' },
  payload: 'h. jon benjamin',
  signature: 'YOWPewyGHKu4Y_0M_vtlEnNlqmFOclqp4Hy6hVHfFT4'
}

jws.createSign(options)

Returns a new SignStream object.

Options:

• header (required)
• payload
• key || privateKey || secret
• encoding (Optional, defaults to 'utf8')

Other than header, all options expect a string or a buffer when the value is known ahead of time, or a stream for convenience.

Example

// This...
jws.createSign({
  header: { alg: 'RS256' },
  privateKey: privateKeyStream,
  payload: payloadStream,
}).on('done', function(signature) {
  // ...
});

// is equivilant to this:
const signer = jws.createSign(
  header: { alg: 'RS256' },
);
privateKeyStream.pipe(signer.privateKey);
payloadStream.pipe(signer.payload);
signer.on('done', function(signature) {
  // ...
});

jws.createVerify(options)

Returns a new VerifyStream object.

Options:

• signature
• key || publicKey || secret
• encoding (Optional, defaults to 'utf8')

All options expect a string or a buffer when the value is known ahead of time, or a stream for convenience.

Example

// This...
jws.createVerify({
  publicKey: pubKeyStream,
  signature: sigStream,
}).on('done', function(verified, obj) {
  // ...
});

// is equivilant to this:
const verifier = jws.createVerify();
pubKeyStream.pipe(verifier.publicKey);
sigStream.pipe(verifier.signature);
verifier.on('done', function(verified, obj) {
  // ...
});

Class: SignStream

A Readable Stream that emits a single data event, the calculated signature, when done.

Event: 'done'

function (signature) { }

signer.payload

A Writable Stream that expects the JWS payload. Do not use if you passed a payload option to the constructor.

Example

payloadStream.pipe(signer.payload);

signer.secret
signer.key
signer.privateKey

A Writable Stream. Expects the JWS secret for HMAC, or the privateKey for ECDSA and RSA. Do not use if you passed a secret or key option to the constructor.

Example:

privateKeyStream.pipe(signer.privateKey);

Class: VerifyStream

This is a Readable Stream that emits a single data event, the result of whether or not that signature was valid.

Event: 'done'

function (valid, obj) { }

valid is a boolean for whether or not the signature is valid.

verifier.signature

A Writable Stream that expects a JWS Signature. Do not use if you passed a signature option to the constructor.

verifier.secret
verifier.key
verifier.publicKey

A Writable Stream that expects a public key or secret. Do not use if you passed a key or secret option to the constructor.

TODO

• It feels like there should be some convenience options/APIs for defining the algorithm rather than having to define a header object with { alg: 'ES512' } or whatever every time.

• X.509 support, ugh

License

MIT

Copyright (c) 2013-2015 Brian J. Brennan

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Changelog

[2.0.0] - 2015-01-30

Changed

• BREAKING: Default payload encoding changed from binary to utf8. utf8 is a is a more sensible default than binary because many payloads, as far as I can tell, will contain user-facing strings that could be in any language. (<code>[6b6de48]</code>)

• Code reorganization, thanks [@fearphage]! (<code>[7880050]</code>)

Added

• Option in all relevant methods for encoding. For those few users that might be depending on a binary encoding of the messages, this is for them. (<code>[6b6de48]</code>)